Maintainer: Jianhai Zhang (jzhan067@ucr.edu; zhang.jianhai@hotmail.com)

1 Summary

This spatialHeatmap package can be used for interactive visualisation as long as a data matrix and an associated SVG image are provided. This tutorial is specifically designed for how to make an SVG image and link it with gene expression matrix. The tutorial requires a png image with regions coloured by different colours, a data matrix, the SVG editor Inkscape, and optionally the image editor GIMP. The png image is the template to make the SVG image while the data matrix is used to fill different regions in the image. Inkscape is used to associate the SVG image with the data matrix and GIMP is optionally used to facilitate making the SVG image.

In the following, the tutorial is given with a gene expression matrix and an associated root tissue image in SVG format as an example, which is just a basic example for users to start. All the files used in this tutorial can be downloaded here (download an SVG image: click the image, right-click, select “Save image as…”; download a PNG image: click the image, click “Download”, right-click, select “Save image as…”; download a TXT file: click the file, click “Raw”, right-click, select “Save as…”.).

Users are advised to pay enough attention to the bold text below, because it can prevent common errors when creating the SVG images.

2 Procedure

2.1 Gene expression matrix

In the gene expression matrix, the row and column names are usually gene IDs and sample/conditions, respectively. The sample/condition names MUST be fomatted this way: a sample name is followed by double underscore then the condition, such as “stele__140mM_48h" (Mustroph et al. 2009), where stele is the sample and 140mM_48h is the condition. One column of meta data (e.g. gene annotation) can also be included in parallel with sample/condition at the end. In the column names of sample/condition and meta data, only letters, digits, single underscore, dots are allowed. Not all samples in the matrix necessarily need to be present in the svg image, and vice versa. Only samples present in the svg image are recognised and coloured. The example of partial gene expression matrix is shown below (Xie 2014; Zhu 2019; Dowle and Srinivasan 2018).

2.2 Make SVG images

2.2.1 Make blank SVG images by drawing

If the contour in the png image is not clear, GIMP can generate low-quality SVG images. In this case, one can draw the blank SVG image with Inkscape by using the png as a template. Below is an example of drawing only two polygons.

  1. Draw polygons

    Open the root png image (Mustroph et al. 2009) in Inkscape. The image can be zoomed by press “-” or “+” on the keyboard. Select the “Draw freeahnd lines (F6)” at the left tool bar. Left click once at the first corner of the polygon, and move to the second corner and double left click, and so on. Lastly, when drawing the last line click at the first corner to seal the polygon.

  2. Align polygons

    Select “Edit path by nodes (F2)” from the left tool bar. Draw a large rectangle to select the whole sealed polygon and draw another large rectangle to select all nodes.

    Click the “Make selected nodes smooth” in the top tool bar. Drag the edges and handles to make the sealed polygon aligned with the template, then the first polygon is finished.

  3. Make polygons with shapes

    Alternatively, the polygons can be made with rectangles. Click “Create rectangles and squares (F4)” at the left tool bar and draw a rectangle in the second template polygon. Select the rectangle and click “Object to Path” under the “Path” tab at the top, then the rectangle becomes an SVG path, which can be edited. Switch cursor to “Select and Transform Objects (F1)” and rotate the rectangle.

    Switch the cursor to “Edit path by nodes (F2)” and select all nodes of the rectangle. Click “Make selected nodes corner” at the top tool bar. Drag the edges and handles to overlay the rectangle path on the template, then the second polygon is finished.

In this root image there are many polygons, so it takes too much time to draw them individually. In order to save time, GIMP can be used to extract the polygons automatically.

2.2.2 Make blank SVG images with GIMP

If the png image contains many polygons and their contour is clear (e.g. the root image), GIMP can be used to automatically extract the polygons.

  1. Open the root png image with GIMP. There are five coloured tissues (skyblue, green, red, yellow, blue). The skyblue is not present in the gene matrix while the green, red, yellow, blue correspond to epidermis, cortex, endodermis, stele in the gene matrix respectively. Enable the “Paths” panel under the “Windows” tab at the top. Right click and select “By Color” under “Select”.

  2. Click on the skyblue tissue, then right click, select “To Path” under “Select”, and the paths of all skyblue tissues are shown in the “Paths” panel.

  3. Similarly, exrtact paths of other tissues. In the “Paths” panel set paths visible by enabling the eye symbol, then right click and merge visible paths. Right click and export merged paths, which is a blank SVG image.

2.2.3 Make blank SVG images with GIMP and drawing

The drawing method produce accurate SVG images but it is time-consuming, while the GIMP method is faster but it can generate fused polygons. In this tutorial, the root png image has well separated polygons and clear contours, so GIMP can produce accurate SVG images. Otherwise the resulting SVG images would have mixed and noise polygons. Considering the pros and cons of two methods, the good practice is to use GIMP to extract polygons first then use drawing the refine the blank SVG image. Below is an example of an SVG image with fused polygons, which is generated by GIMP.

  1. Place all SVG paths inside a layer

    Open the blank fused SVG image in Inkscape (the image can be zoomed by press “-” or “+” on the keyboard). Under the “Layers” tab at the top click “Layers”, the “Layers” panel will come out on the right, then click “+” at the bottom left corner of the panel to add “Layer 1”.

    Draw a rectangle over the fused SVG graph and cut. Then click on “Layer 1” and paste the fused SVG to “Layer 1” (make sure the “Layer 1” is unlocked by refering to the lock symbol). Open the “XML Editor” from the “Edit” tab at the top, if “<svg:path id=”path 77“>” is under “<svg:g id=”layer1" inkscape:label=“Layer 1”>“, then the fused SVG is inside "Layer 1" for sure.

  2. Refine and modify the SVG image

    Draw a ractangle over the image, click “Break Apart” under the “Path” tag, then select the outer noisy rectangle by clicing on its edge. Press “delete” on the keyboard to delete it.

    Click on the edge of large fused polygon and move. Use the drawing method to make new polygons (blue) with the fused ones as templates. Place back the new polygons to make the tissue complete.

If a large fused polygon needs to be separated, one can use the eraser tool. Drag the fused polygon away from the tissue, select the eraser tool from the left tool bar, then use the eraser to cut the fused polygon into three independent polygons. Select the cut polygons and click “Break Apart” under the “Path” tab at the top, then the three polygons are entirely separated. Place back the three polygons to make the tissue complete.

  1. Fill and stroke

    Under “Object” tab at the top, select “Fill and Stroke…”, then the “Fill and Stroke (Shift+Ctrl+F)” panel will come out on the right. Select all polygons by drawing a large rectangle over them.

    Under the “Stroke paint” tab in the fill and stroke panel, select “Flat color”. Must make sure the “Alpha (opacity)” is 255, “Opacity(%)” is 100.0, and “Blur(%)” is 0.0 . Under the “Stroke style” tab, set the stroke width, e.g.: 1.5 px.

    Under the “Fill” tab, click “No paint”, then the resulting blank SVG image is ready to be used in next section.

2.4 Add text to label tissues

Users can add text to label tissues. Basically, the text is first typed in with the text tool and then the text object is coverted to paths. Next text paths are added into the polygon group of target tissue and filled with the same tissue colour.

  1. Creat text paths

    Select “Creat and select text objects (F8)” from the left tool bar, drag a text box, and type (epidermis). Click on the text object and convert it to path.

  2. Text fill and stroke

    Click on the text paths and fill them with the same colour of target tissue using “Pick colors from image (F7)” from the left tool bar. In the “Fill and Stroke” panel, set the stroke style and make sure the “Alpha (opacity)” is 255, “Opacity(%)” is 100.0, and “Blur(%)” is 0.0 for both fill and stroke .

  3. Add text paths to tissue group

    Click and cut the text. Double click the target tissue (epidermis, green) to enter the group.

    Paste the text anywhere and move/resize it, then right click the text and ungroup it.

    All the text paths are in the target tissue group (epidermis).

To add a pointer, draw a rectangle and convert it to path, fill it with the same style as the target tissue, then move, rotate and resize it.

Click one of any other tissues, then drag the target tissue to see the text and pointer are grouped together with the target.

Similarly, add text to other tissues.

  1. Save the final SVG graph, which is ready to use in the spatialHeatmap. The name of saved SVG image can only consists of letters, digits, underscores. E.g. “root_cross_final.svg” is acceptable while “root_cross_final(copy).svg” will give errors.

2.5 Troubleshooting

The process of making SVG file is error-prone, if errors arise in the Spatial Heatmap app, such as some tissues are missing, then users are advised to double check the bold text above.

3 Reference

https://www.w3schools.com/graphics/svg_intro.asp
https://www.gimp.org/tutorials/
https://inkscape.org/en/doc/tutorials/advanced/tutorial-advanced.en.html

Dowle, Matt, and Arun Srinivasan. 2018. Data.table: Extension of ‘Data.frame‘. https://CRAN.R-project.org/package=data.table.

Mustroph, Angelika, M Eugenia Zanetti, Charles J H Jang, Hans E Holtan, Peter P Repetti, David W Galbraith, Thomas Girke, and Julia Bailey-Serres. 2009. “Profiling Translatomes of Discrete Cell Populations Resolves Altered Cellular Priorities During Hypoxia in Arabidopsis.” Proc Natl Acad Sci U S A 106 (44): 18843–8.

Xie, Yihui. 2014. “Knitr: A Comprehensive Tool for Reproducible Research in R.” In Implementing Reproducible Computational Research, edited by Victoria Stodden, Friedrich Leisch, and Roger D. Peng. Chapman; Hall/CRC. http://www.crcpress.com/product/isbn/9781466561595.

Zhu, Hao. 2019. KableExtra: Construct Complex Table with ’Kable’ and Pipe Syntax. https://CRAN.R-project.org/package=kableExtra.